feat(checkpoint): wire checkpointing into agent event loop - #2190

Description

Wires the Checkpoint data model (landed in #2181) into the agent runtime so an opt-in checkpointing=True agent pauses at ReAct cycle boundaries and emits a serializable pause-point marker. The marker travels through AgentResult.checkpoint and is passed back to a fresh agent through a checkpointResume block. The design mirrors the existing interrupt pattern: stop_reason="checkpoint" to signal the pause, content-block resume, no new method surface to learn.

A Checkpoint is a position marker (which boundary fired and which cycle index), not a state snapshot. State persistence is the caller's responsibility. The recommended pairing is a SessionManager for state continuity plus checkpointing=True for boundary signalling.

User-facing API (zero breaking changes — opt-in only):

from strands import Agent
from strands.session import FileSessionManager

agent = Agent(
    tools=[...],
    session_manager=FileSessionManager(session_id="run-1", storage_dir="..."),
    checkpointing=True,
)

result = await agent.invoke_async("do the thing")

while result.stop_reason == "checkpoint":
    save_somewhere(result.checkpoint.to_dict())
    # later, possibly in a fresh process / activity:
    fresh = Agent(
        tools=[...],
        session_manager=FileSessionManager(session_id="run-1", storage_dir="..."),
        checkpointing=True,
    )
    result = await fresh.invoke_async(
        {"checkpointResume": {"checkpoint": load_somewhere()}}
    )

print(result.message)  # stop_reason == "end_turn"

V0 known limitations:

• Metrics reset on each resume call.
• OpenAIResponsesModel(stateful=True) not supported.
• BeforeInvocationEvent / AfterInvocationEvent fire on every resume (same as interrupts).
• Per-tool granularity within a cycle requires a custom ToolExecutor. The SDK checkpoint operates at cycle boundaries.
• Streaming callbacks do not re-emit on replay.

Related Issues

Documentation PR

Type of Change

New feature

Testing

Verified the changes do not break functionality or introduce warnings in consuming repositories.

• I ran hatch run prepare

Evidence from fresh runs:

• hatch test — 3026 passed, 4 skipped, 0 failed.
• hatch run hatch-static-analysis:lint-check — ruff check and mypy both clean.
• hatch run hatch-static-analysis:format-check — all files formatted.\

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly (user-guide page is a follow-up PR in agent-docs; module-level docstring in checkpoint.py covers V0 limitations, precedence rules, and the recommended SessionManager pairing)
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed (reference Temporal / Dapr / Step Functions examples are the next milestone in the durable-execution tracking plan)
• My changes generate no new warnings
• Any dependent changes have been merged and published (Part A — feat: introduce checkpoint in experimental #2181 — is merged on main; this PR builds on it)

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.